import-meta-resolve

What is import-meta-resolve?

The import-meta-resolve package provides utilities for resolving module specifiers in the same way that Node.js does for ES modules. It allows developers to programmatically resolve specifiers from the context of a specific file or URL, which can be useful for tooling that needs to understand module resolution, bundlers, and other development tools.

What are import-meta-resolve's main functionalities?

Resolving module specifiers

This feature allows you to resolve the full path of a module specifier from a specific context, typically the URL of the importing module. The code sample demonstrates how to use the resolve function to find the full path of 'some-module' as if it were being imported from the current module.

import { resolve } from 'import-meta-resolve';

(async () => {
  const resolved = await resolve('some-module', import.meta.url);
  console.log(resolved);
})();

Other packages similar to import-meta-resolve

resolve

The 'resolve' package is a popular Node.js module resolution algorithm that can be used programmatically. It is similar to import-meta-resolve but does not specifically target ES module resolution semantics. It is more general-purpose and can resolve CommonJS modules as well.

enhanced-resolve

This package is used internally by webpack to resolve module paths. It is highly configurable and can handle complex resolution scenarios, including loaders and plugin systems. While it offers more features than import-meta-resolve, it is also more complex and tailored to webpack's ecosystem.

README

import-meta-resolve

Resolve things like Node.js. Ponyfill for import.meta.resolve. Supports import maps, export maps, loading CJS and ESM projects, all of that!

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install import-meta-resolve

Use

import {resolve} from 'import-meta-resolve'

main()

async function main() {
  // A file:
  console.log(await resolve('./index.js', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/index.js

  // A CJS package:
  console.log(await resolve('builtins', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/builtins/index.js

  // A scoped CJS package:
  console.log(await resolve('@babel/core', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/@babel/core/lib/index.js

  // A package with an export map:
  console.log(await resolve('tape/lib/test', import.meta.url))
  //=> file:///Users/tilde/Projects/oss/import-meta-resolve/node_modules/tape/lib/test.js
}

API

This package exports the following identifiers: resolve, moduleResolve. There is no default export.

resolve(specifier, parent)

Match import.meta.resolve except that parent is required (you should probably pass import.meta.url).

Parameters

• specifier (string) — /example.js, ./example.js, ../example.js, some-package
• parent (string, example: import.meta.url) Full URL (to a file) that specifier is resolved relative from

Returns

Returns a promise that resolves to a full file:, data:, or node: URL to the found thing.

moduleResolve(specifier, parent[, conditions])

The “Resolver Algorithm Specification” as detailed in the Node docs (which is sync and slightly lower-level than resolve).

Parameters

• specifier (string) — /example.js, ./example.js, ../example.js, some-package
• parent (URL, example: import.meta.url) Full URL (to a file) that specifier is resolved relative from
• conditions (Set<string>, default: new Set('node', 'import')) Conditions

Returns

A URL object to the found thing.

Algorithm

The algorithm for resolve matches how Node handles import.meta.resolve, with a couple of differences.

The algorithm for moduleResolve matches the Resolver Algorithm Specification as detailed in the Node docs (which is sync and slightly lower-level than resolve).

Differences to Node

• parent defaulting to import.meta.url cannot be ponyfilled: you have to explicitly pass it
• No support for CLI flags: --experimental-specifier-resolution, --experimental-json-modules, --experimental-wasm-modules, --experimental-policy, --input-type, --preserve-symlinks, --preserve-symlinks-main, nor --conditions work
• No attempt is made to add a suggestion based on how things used to work in CJS before to not-found errors
• Prototypal methods are not guarded: Node protects for example String#slice or so from being tampered with, whereas this doesn’t

Errors

• ERR_INVALID_MODULE_SPECIFIER — when specifier is invalid
• ERR_INVALID_PACKAGE_CONFIG — when a package.json is invalid
• ERR_INVALID_PACKAGE_TARGET — when a package.json exports or imports is invalid
• ERR_MODULE_NOT_FOUND — when specifier cannot be found in parent
• ERR_PACKAGE_IMPORT_NOT_DEFINED — when a local import is not defined in an import map
• ERR_PACKAGE_PATH_NOT_EXPORTED — when an export is not defined in an export map
• ERR_UNSUPPORTED_DIR_IMPORT — when attempting to import a directory

License

MIT © Titus Wormer